/**
 * ============运势路由配置模块开始===========
 * 运势路由配置 - Fortune Routes Configuration
 * 
 * 功能说明：
 * - 提供运势相关的API端点
 * - 支持每日运势和生肖运势查询
 * - 集成认证中间件保护需要登录的接口
 * - 提供RESTful风格的API接口
 * 
 * 依赖模块：
 * - express: Web框架，提供路由功能
 * - fortuneController: 运势控制器，包含业务逻辑处理
 * - authMiddleware: 认证中间件，验证JWT令牌
 * 
 * API端点说明：
 * - GET /fortune/daily - 获取每日运势（公开接口）
 * - GET /fortune/zodiac - 获取生肖运势（公开接口）
 * - GET /fortune/personal - 获取个人运势（需要认证）
 * - GET /fortune/analysis - 获取运势分析（需要认证）
 * 
 * 应用场景：
 * - 运势查询应用的数据接口
 * - 传统文化相关应用
 * - 个性化运势推荐
 * - 命理学分析工具
 * 
 * 设计原则：
 * - RESTful API设计
 * - 统一的响应格式
 * - 完善的错误处理
 * - 分层的访问控制
 * 
 * Provides comprehensive fortune API endpoints with authentication support
 */

// 导入必要的依赖包 - Import necessary dependencies
import express from 'express';                                    // Web框架 - Web framework
import fortuneController from '../controllers/fortuneController.js'; // 运势控制器 - Fortune controller
import authMiddleware from '../middleware/auth.js';               // 认证中间件 - Authentication middleware

/**
 * ============路由实例创建开始===========
 * 创建Express路由实例
 * Create Express router instance
 * 
 * 功能说明：
 * - 创建模块化的路由处理程序
 * - 支持路由级别的中间件和参数处理
 * - 可以像中间件一样挂载到应用程序上
 * - 提供灵活的路由组织方式
 * 
 * 使用方式：
 * - 在主应用中通过 app.use('/api/fortune', fortuneRoutes) 挂载
 * - 所有路由都会自动添加 /api/fortune 前缀
 * - 支持路由级别的中间件应用
 */
const router = express.Router();                                  // 创建路由实例 - Create router instance

/**
 * ============公开路由（无需认证）开始===========
 * Public routes (no authentication required)
 * 
 * 这些路由不需要用户登录即可访问，主要用于：
 * - 通用运势查询功能
 * - 生肖运势查询
 * - 万年历信息获取
 * - 公开的运势数据展示
 * 
 * 安全考虑：
 * - 虽然是公开路由，但仍需要进行参数验证
 * - 实施频率限制防止恶意请求
 * - 返回通用数据，不涉及用户隐私
 * - 避免暴露敏感的系统信息
 */

/**
 * ============获取每日运势功能开始===========
 * 获取每日运势（公开接口）
 * Get daily fortune (public endpoint)
 * 
 * @route GET /api/fortune/daily
 * @access Public - 公开访问，无需认证
 * @param {string} [date] - 查询日期，格式：YYYY-MM-DD，可选，默认为今天
 * @returns {Object} 响应对象包含每日运势信息
 * @throws {400} 日期格式错误
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 获取指定日期的通用每日运势信息
 * - 包含万年历信息、宜忌事项、节气等
 * - 不需要用户登录，返回通用运势数据
 * - 支持历史日期和未来日期查询
 * - 基于传统文化算法计算运势
 * 
 * 查询参数：
 * - date: 日期，格式YYYY-MM-DD，可选，默认今天
 * 
 * 请求示例：
 * GET /api/fortune/daily
 * GET /api/fortune/daily?date=2024-01-01
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "date": "2024-01-01",
 *     "calendar": {
 *       "lunar": "甲辰年十一月初一",
 *       "ganzhi": "甲辰年丙子月甲子日",
 *       "zodiac": "龙",
 *       "constellation": "摩羯座"
 *     },
 *     "yiJi": {
 *       "yi": ["祭祀", "祈福", "求嗣"],
 *       "ji": ["嫁娶", "出行", "动土"]
 *     },
 *     "solarTerm": {
 *       "current": "冬至",
 *       "next": "小寒",
 *       "daysToNext": 15
 *     },
 *     "fortune": {
 *       "overall": 75,
 *       "description": "今日运势平稳，适合稳扎稳打"
 *     }
 *   },
 *   "message": "获取每日运势成功"
 * }
 * 
 * 异常处理：
 * - 400: 日期格式错误或参数无效
 * - 500: 服务器内部错误或数据获取失败
 * 
 * 性能考虑：
 * - 支持结果缓存以提高响应速度
 * - 对频繁查询的日期进行预计算
 * - 实施合理的频率限制
 */
router.get('/daily', fortuneController.getDailyFortune);

/**
 * ============获取生肖运势功能开始===========
 * 获取生肖运势（公开接口）
 * Get zodiac fortune (public endpoint)
 * 
 * @route GET /api/fortune/zodiac
 * @access Public - 公开访问，无需认证
 * @param {string} zodiac - 生肖名称（鼠、牛、虎、兔、龙、蛇、马、羊、猴、鸡、狗、猪）
 * @param {string} [date] - 查询日期，格式：YYYY-MM-DD，可选，默认为今天
 * @returns {Object} 响应对象包含生肖运势信息
 * @throws {400} 生肖名称无效或日期格式错误
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 获取指定生肖在指定日期的运势信息
 * - 包含各项运势评分、幸运数字、颜色、方向等
 * - 基于五行相生相克理论计算运势
 * - 支持12生肖的运势查询
 * - 提供详细的运势分析和建议
 * 
 * 查询参数：
 * - zodiac: 生肖名称，必需，支持中文生肖名
 * - date: 日期，格式YYYY-MM-DD，可选，默认今天
 * 
 * 请求示例：
 * GET /api/fortune/zodiac?zodiac=龙
 * GET /api/fortune/zodiac?zodiac=龙&date=2024-01-01
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "zodiac": "龙",
 *     "date": "2024-01-01",
 *     "element": "土",
 *     "fortune": {
 *       "overall": 85,
 *       "love": 80,
 *       "career": 90,
 *       "wealth": 75,
 *       "health": 85,
 *       "study": 80
 *     },
 *     "level": "上吉",
 *     "description": "今日运势极佳，是实现目标的绝佳时机",
 *     "advice": "把握机会，积极行动",
 *     "lucky": {
 *       "numbers": [3, 7, 9],
 *       "colors": ["金色", "红色"],
 *       "direction": "东南"
 *     },
 *     "avoid": {
 *       "numbers": [2, 4],
 *       "colors": ["黑色", "灰色"],
 *       "direction": "西北"
 *     }
 *   },
 *   "message": "获取生肖运势成功"
 * }
 * 
 * 异常处理：
 * - 400: 生肖名称无效或日期格式错误
 * - 500: 服务器内部错误或运势计算失败
 * 
 * 算法说明：
 * - 基于传统五行相生相克理论
 * - 结合天干地支计算方法
 * - 考虑节气和月相影响
 * - 融入现代统计学方法
 */
router.get('/zodiac', fortuneController.getZodiacFortune);

/**
 * ============获取个人运势功能开始===========
 * 获取个人运势（需要认证）
 * Get personal fortune (authentication required)
 * 
 * @route GET /api/fortune/personal
 * @access Private - 需要JWT认证
 * @middleware authMiddleware - 验证用户身份
 * @param {string} [date] - 查询日期，格式：YYYY-MM-DD，可选，默认为今天
 * @returns {Object} 响应对象包含个人运势信息
 * @throws {401} 未授权访问
 * @throws {400} 日期格式错误
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 基于用户个人信息计算专属运势
 * - 结合用户生日、生肖等信息
 * - 提供个性化的运势分析和建议
 * - 支持运势历史记录查询
 * - 需要用户登录后才能访问
 * 
 * 认证要求：
 * - 需要在请求头中提供有效的JWT令牌
 * - Authorization: Bearer <token>
 * - 令牌必须包含有效的用户信息
 * 
 * 请求示例：
 * GET /api/fortune/personal
 * Headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "userId": "user123",
 *     "date": "2024-01-01",
 *     "personalInfo": {
 *       "zodiac": "龙",
 *       "element": "土",
 *       "birthYear": 1988
 *     },
 *     "fortune": {
 *       "overall": 88,
 *       "love": 85,
 *       "career": 92,
 *       "wealth": 78,
 *       "health": 90
 *     },
 *     "personalizedAdvice": "根据您的八字分析，今日适合...",
 *     "luckyItems": {...},
 *     "warnings": [...]
 *   },
 *   "message": "获取个人运势成功"
 * }
 */
router.get('/personal', authMiddleware, fortuneController.getPersonalFortune);

/**
 * ============获取运势分析功能开始===========
 * 获取运势分析（需要认证）
 * Get fortune analysis (authentication required)
 * 
 * @route GET /api/fortune/analysis
 * @access Private - 需要JWT认证
 * @middleware authMiddleware - 验证用户身份
 * @param {string} [period] - 分析周期（daily/weekly/monthly），可选，默认daily
 * @param {string} [startDate] - 开始日期，格式：YYYY-MM-DD
 * @param {string} [endDate] - 结束日期，格式：YYYY-MM-DD
 * @returns {Object} 响应对象包含运势分析信息
 * @throws {401} 未授权访问
 * @throws {400} 参数格式错误
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 提供深度的运势分析报告
 * - 支持不同时间周期的分析
 * - 包含趋势预测和建议
 * - 基于用户历史数据进行分析
 * - 提供图表化的数据展示
 * 
 * 查询参数：
 * - period: 分析周期，可选值：daily/weekly/monthly
 * - startDate: 开始日期，格式YYYY-MM-DD
 * - endDate: 结束日期，格式YYYY-MM-DD
 * 
 * 请求示例：
 * GET /api/fortune/analysis?period=weekly
 * Headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
 * 
 * 响应格式：
 * {
 *   "success": true,
 *   "data": {
 *     "period": "weekly",
 *     "dateRange": {
 *       "start": "2024-01-01",
 *       "end": "2024-01-07"
 *     },
 *     "analysis": {
 *       "trend": "上升",
 *       "averageScore": 82,
 *       "bestDay": "2024-01-03",
 *       "worstDay": "2024-01-05"
 *     },
 *     "recommendations": [...],
 *     "chartData": [...]
 *   },
 *   "message": "获取运势分析成功"
 * }
 */
router.get('/analysis', authMiddleware, fortuneController.getFortuneAnalysis);

/**
 * ============公开路由结束===========
 * End of public routes
 * 
 * 注意事项：
 * - 公开路由虽然无需认证，但仍需要进行严格的参数验证
 * - 建议在生产环境中对这些路由实施频率限制
 * - 返回的数据应该是通用的，不包含用户个人信息
 * - 需要考虑缓存策略以提高性能
 */

/**
 * ============路由导出开始===========
 * 导出路由配置供应用使用
 * Export router configuration for app use
 * 
 * 使用说明：
 * - 在主应用文件中导入此路由配置
 * - 通过 app.use('/api/fortune', fortuneRoutes) 挂载到应用
 * - 所有路由将自动获得 /api/fortune 前缀
 * 
 * 示例：
 * import fortuneRoutes from './routes/fortune.js';
 * app.use('/api/fortune', fortuneRoutes);
 * 
 * 路由映射：
 * - GET /api/fortune/daily -> 获取每日运势
 * - GET /api/fortune/zodiac -> 获取生肖运势
 * - GET /api/fortune/personal -> 获取个人运势（需认证）
 * - GET /api/fortune/analysis -> 获取运势分析（需认证）
 */
export default router;
// ============运势路由配置模块结束===========